home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / os2 / pmp43.zip / DBUG.TXT < prev    next >
Text File  |  1996-07-06  |  16KB  |  468 lines
  1. ******************************************************************************
  2. DBug Definition
  3. ******************************************************************************
  4. DBug is a flexable and easy to use real-time Debugger for the software
  5. engineer/developer that provides debugging capabilities that are impossible
  6. for the source-level debugger, easier to use, and often more convenient.
  7.  
  8. The concept of DBug is simple. You place 1 or more "DBUG" statements in your
  9. program source code at a strategic point for the purpose of displaying a
  10. message, the content of variables or memory, or time stamping a point of entry.
  11.  
  12. Compile and run your program(s). While or after running your program(s), you
  13. can view the current results via the "DBug" window or view the DBug log file
  14. to browse your DBug results.
  15.  
  16.  
  17. ******************************************************************************
  18. Using DBug
  19. ******************************************************************************
  20. When you compile your programs you include the C/C++ header file "dbug.h" and
  21. specify the compiler directive "-DDEBUG". You must link your program with the
  22. DBug Import Library "DBUGAPI.LIB" to resolve externs.
  23.  
  24. Once you're done testing and want to remove the DBUG statements for
  25. "production" use, you may:
  26.  
  27.   1.  Recompile your program(s) WITHOUT specifying the compiler directive
  28.       "-DDEBUG". The compiler will ignore the DBUG statements. Linking with
  29.       "DBUGAPI.LIB" is now unnecessary.
  30.  
  31.   2.  Manually remove each DBUG statement. Recompile and link.
  32.  
  33. It is recommended is that you leave the "dbug.h" include file in the
  34. program(s) and choose option 1 above. This allows you to, with just a
  35. recompile, have your run-time debugging enabled quickly for testing.
  36.  
  37. DBUG statements are C/C++ macros which map to a single API. There is a
  38. "generic" DBUG macro for any use, and specific macros for each unique
  39. standard C data type&colon.
  40.  
  41.   o  The DBUG macro is generic and allows you to display the contents from
  42.      any data type as well as any chunk of memory.
  43.   o  The DBUGM macro displays a simple message of your choice.
  44.   o  The DBUGS macro displays the contents of a SHORT data type.
  45.   o  The DBUGL macro displays the contents of a LONG data type.
  46.   o  The DBUGI macro displays the contents of a INTEGER data type.
  47.   o  The DBUGD macro displays the contents of a DOUBLE data type.
  48.   o  The DBUGC macro displays the contents of a CHAR data type.
  49.   o  The DBUGZ macro displays the contents of a String data type.
  50.   o  The DBUGP macro displays the contents of a POINTER data type.
  51.   o  The DBUGOPEN macro opens a new DBug log file
  52.   o  The DBUGCLOSE macro closes a the DBug log file
  53.   o  The DBUGSTOP macro terminates the DBug facility
  54.  
  55. Each DBUG statement will cause an IPC message to be build and sent to the
  56. central DBug program. The DBug program will then display the message in his
  57. standard format and log it for later recall - if logging is turned on.
  58.  
  59. If the DBug proram is not presently running to receive these requests, your
  60. DBUG statements will be ignored at run-time. The effort required to complete
  61. a single DBUG within your program(s) is very minimal and insignificant.
  62.  
  63. The DBug program can be started and stopped at any time - even when programs
  64. are actively DBUGing. If restarted, DBug will continue pulling DBUGs from his
  65. queue and displaying/logging them.
  66.  
  67. DBug will handle bursts of DBUGs easily as he offers a 256K maximum buffer.
  68. DBug will only allocate/commit enough memory to hold each DBUG request - not
  69. the whole 256K. The 256K buffer is therefore used optimally and requires
  70. little real memory from OS/2.
  71.  
  72. When monitoring DBug, minimize the window if large amounts of DBUGs are be
  73. displayed. This will significantly improve how fast DBug displays and reduce
  74. the overhead of displaying results.
  75.  
  76. DBug has two log files and are created in the drive/directory where DBug was
  77. started. If started and control from PM Patrol, these log files will reside
  78. in the directory from where PM Patrol was installed and started.
  79.  
  80.   o  The primary and active log "DBUG.LOG" contains current data.
  81.  
  82.   o  The backup log "DBUG.BAK" contains the previous primary data after a new
  83.       log file is opened.
  84.  
  85. When logging is opened, a DBUG message is placed at the beginning of the Dbug
  86. log file.
  87.  
  88. Note: DBug log files are automatically recycled at midnight so that under
  89. continuous operation, each log will contain a full 24 hours of information.
  90. Therefore, up to 2 days (primary and backup) of DBug information can be
  91. reviewed any time.
  92.  
  93. If Dbug has nothing to do, absolutely no CPU is used. The small amount of
  94. DBug memory requirements are "swappable" to make room for more active
  95. demanding programs. 
  96.  
  97. DBug is a high performance debugging tool for even the most intense
  98. environments. When the Dbug window is minimized or DBug is running in "Quiet"
  99. mode, DBug can handle several hundred DBUGs per second. Even more for highend
  100. Pentium or PowerPC processors.
  101.  
  102.  
  103. ******************************************************************************
  104. DBug Programming Files
  105. ******************************************************************************
  106. The DBug software contains 3 files for DBug programming purposes&colon.
  107.  
  108.   o  DBUG.H is a C/C++ header containing the macros for DBug. "Include"
  109.      this header file in your C/C++ programs.
  110.  
  111.   o  DBUGAPI.LIB is the Import Library to link with to resolve DBUG APIs. You
  112.      must link (LINK386) with this Import Library to resolve external
  113.      references and is specified in the LINK386 options.
  114.  
  115.   o  DBUGAPI.DLL is the Dynamic Link Library which holds the actual code of APIs
  116.  
  117. For compiling and linking, append the installation path used for PM Patrol to
  118. the following statements in your CONFIG.SYS:
  119.  
  120.   o  "LIB" statement for the API import library (DBUGAPI.LIB).
  121.  
  122.   o  "INCLUDE" statement for the API C/C++ header (DBUG.H).
  123.  
  124. Make sure the DBug DLL is available at run time by appending the installtion
  125. path used for PM Patrol to the following statements in your CONFIG.SYS
  126. file:
  127.  
  128.   o  "LIBPATH" statement for the API DLL (DBUGAPI.DLL).
  129.  
  130.  
  131. ******************************************************************************
  132. DBug Macro Set
  133. ******************************************************************************
  134.  
  135. DBUG() Macro
  136. ------------------------------------------------------------------------------
  137. The DBUG macro is generic and allows you to display the contents from any
  138. data type as well as any chunk of memory.
  139.  
  140. Prototype: ULONG  DBUG (PVOID address, USHORT size, PCHAR note)
  141.  
  142. Parms:     address            ... Address to displayed/dumped
  143.            size               ... Size of data type or memory to be display
  144.            note               ... A personal description of your choice
  145.  
  146. Returns:   NO_ERROR           ... Successful with no errors, or error code
  147.  
  148. Example:
  149. --------------
  150. #include <stdio.h>
  151. #include <stdlib.h>
  152. #include <dbug.h>
  153.   ...
  154.  
  155.   CHAR   array[60];
  156.  
  157.   DBUG(array, sizeof(array), "my array");
  158.  
  159.  
  160. DBUGM() Macro
  161. ------------------------------------------------------------------------------
  162. The DBUGM macro displays a simple message of your choice.
  163.  
  164. Prototype: ULONG  DBUGM(PCHAR message)
  165.  
  166. Parms:     message            ... A personal description of your choice
  167.  
  168. Returns:   NO_ERROR           ... Successful with no errors, or error code
  169.  
  170. Example:
  171. ----------
  172. #include <stdio.h>
  173. #include <stdlib.h>
  174. #include <dbug.h>
  175.   ...
  176.  
  177.   DBUGM("Point 1 of program");
  178.  
  179.  
  180. DBUGS() Macro
  181. ------------------------------------------------------------------------------
  182. The DBUGS macro displays the contents of a SHORT data type.
  183.  
  184. Prototype: ULONG  DBUGS(PSHORT address, PCHAR note)
  185.  
  186. Parms:     address            ... Address of short to be displayed
  187.            note               ... A personal description of your choice
  188.  
  189. Returns:   NO_ERROR           ... Successful with no errors, or error code
  190.  
  191. Example:
  192. ----------
  193. #include <stdio.h>
  194. #include <stdlib.h>
  195. #include <dbug.h>
  196.  ...
  197.  
  198.   USHORT  variable;
  199.  
  200.   DBUGS(&.variable, "my variable");
  201.  
  202.